IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / Vk / VkTabPanel.z / VkTabPanel

Wrap

Text File | 1998-10-20 | 29.4 KB | 793 lines

VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) NNNNAAAAMMMMEEEE VkTabPanel - A component for displaying a tabular control panel IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM VkComponent : VkCallbackObject HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <Vk/VkTabPanel.h> PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr VkTabPanel(char* name, Widget parent, Boolean horizOrientation = True, int tabHeight = 0); virtual void ~VkTabPanel(void); CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn Pixel getSelectedTabBg(void); Pixel getUnselectedTabBg(void); Boolean horiz(void); Boolean uniformTabs(void); int size(void); Pixel tabBg(void); Pixel selectedTabBg(void); Pixel labelFg(void); Pixel labelBg(void); GC gc(void); int lineThickness(void); PPPPaaaaggggeeee 1111 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) int tabHeight(void); SSSSeeeettttuuuupppp FFFFuuuunnnnccccttttiiiioooonnnnssss int addTab(char* label, void* clientData, Boolean sorted = False); void addTabs(char** labels, void** clientData, int numLabels, Boolean sorted = False); Boolean removeTab(int index); Boolean removeTab(char* label); Boolean tabPixmap(int index, Pixmap* pixmap_return); Boolean tabPixmap(char* label, Pixmap* pixmap_return); Boolean setTabPixmap(int index, Pixmap pixmap); Boolean setTabPixmap(char* label, Pixmap pixmap); Boolean setTabLabel(int index, char* label); Boolean setTabClientData(int index, void* clientData); TTTTaaaabbbb WWWWiiiiddddtttthhhh FFFFuuuunnnnccccttttiiiioooonnnnssss int getTabWidth (int index=0); int getMaxTabWidth (); void matchTabWidth (VkTabPanel* panel=NULL, enum VK_TAB_MATCH_WIDTH =VK_DEFAULT); void setTabWidth (int width=0); PPPPaaaaggggeeee 2222 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) void setTabWidth (char*); AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss int selectedTab(void); Boolean getTab(int index, char** label_return, void** clientData_return); Widget area1(void); Widget area2(void); XXXX RRRREEEESSSSOOOOUUUURRRRCCCCEEEESSSS AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD WWWWIIIITTTTHHHH TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS additionalMarginHeight Added to tab label margin additionalMarginWidth Added to tab label margin background Background component color, around tabs darkPercent Set the unselected tabs' background to a color that is this percentage of the way between the selected tab's background color and the selected tab's BottomShadow color. endMultiplier End-indicator duplication (3) endSpacing End-indicator internal spacing (9) lineThickness Thickness of tab edges (1) margin Margin between tab edges and the component edge (5) margin1 Margin between workarea1 and the tabs (5) margin2 Margin between workarea2 and the tabs (5) pixmapSpacing Spacing between tab label and pixmap (3) selectedTabBackground Different background used for the selected tab (none) sideOffset Tab edge curvature (17) tabHeight Tab height (0, use label height) tabLabel.background Background used for tabs, bitmaps PPPPaaaaggggeeee 3333 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) tabLabel.fontList Font used for tab labels tabLabel.foreground Foreground used for tab labels, bitmaps tabLabel.height Tab height default if tabHeight is 0 tabLabel.marginHeight Tab label margin tabLabel.marginWidth Tab label margin uniformTabs Whether tabs should be all the same width (False) use3DTabs Draw the tabs with a shaded, 3-D, appearance CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN VkTabPanel presents a row or column of overlayed tabs. One tab is always selected, and appears on top of all the others. The user can left-click on a tab to select it. If the orientation is horizontal, work areas are provided to the left and right of the tab display for application use. If the orientation is vertical, work areas are provided above and below the tab display. When the tabs do not fit within the provided space, end-indicators appear as necessary to represent a set of collapsed tabs. When the user left-clicks or right-clicks in an end-indicator, a popup menu appears listing all the tabs. The user may choose an item to select the corresponding tab. DDDDEEEERRRRIIIIVVVVIIIINNNNGGGG SSSSUUUUBBBBCCCCLLLLAAAASSSSSSSSEEEESSSS A private class, VkTabArea, does virtually all of the work. VkTabPanel creates a VkTabArea amongst the work areas and other Motif widgets. VkTabArea's public interface is the same as VkTabPanel's interface. Many of the VkTabPanel methods simply call the corresponding VkTabArea methods. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll(((()))) VkTabPanel(char* name, Widget parent, Boolean horizOrientation = True, int tabHeight = 0); virtual void ~VkTabPanel(void); PPPPaaaaggggeeee 4444 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VkTabPanel creates a component using the name and parent parameters. The optional horizOrientation argument can be used to create a vertically-oriented VkTabPanel instead of the default horizontal orientation. The tabHeight argument defaults to 0, indicating that the default label height should determine the height of the tabs. Applications which display pixmaps in the tabs may want to specify a height for the tabs. ggggeeeettttSSSSeeeelllleeeecccctttteeeeddddTTTTaaaabbbbBBBBgggg(((()))) Pixel getSelectedTabBg(void); Returns the color used for the selected tab background. This color is set by the "selectedTabBackground" resource. If no resource value is specified, the normal tab background color is used. ggggeeeettttUUUUnnnnsssseeeelllleeeecccctttteeeeddddTTTTaaaabbbbBBBBgggg(((()))) Pixel getUnselectedTabBg(void); Returns the color used for the unselected tab background. This color is a calculated value. hhhhoooorrrriiiizzzz(((()))) Boolean horiz(void); This function returns TRUE if the tab component is horizontally- oriented, FALSE otherwise. uuuunnnniiiiffffoooorrrrmmmmTTTTaaaabbbbssss(((()))) Boolean uniformTabs(void); This function returns TRUE if the tabs have a uniform width (or height, if the tab component is vertically-oriented). By default, tabs take on the necessary width to display their label and pixmap. If the "uniformTabs" resource is set to "true", all tabs take on the width of the largest tab in the group. The total width of a tab is the sum of its label width and if it has a non-NULL pixmap, the pixmap spacing plus the pixmap size. The pixmap spacing is set by the "pixmapSpacing" resource of the VkTabPanel baseWidget, which defaults to 3. Also included is the tab margin width, which is set by the "marginWidth" resource of the "tabLabel" widget created by VkTabPanel plus the "additionalMarginWidth" resource of the VkTabPanel baseWidget, which defaults to 4. When the tabs are displayed, the amount of overlap is set by the "sideOffset" resource of the VkTabPanel baseWidget, which defaults to 17. When the tabs do not fit within the provided space, end- PPPPaaaaggggeeee 5555 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) indicators are displayed. Their appearances are set by the "endSpacing" and "endMultiplier" resources which affect the line spacing and number of lines drawn. They default to 9 and 3, respectively. ssssiiiizzzzeeee(((()))) int size(void); Returns the number of tabs in the group. ttttaaaabbbbBBBBgggg(((()))) Pixel tabBg(void); Returns the color used for the background area underneath the tabs. This color is set by the "background" resource of the VkTabPanel baseWidget. sssseeeelllleeeecccctttteeeeddddTTTTaaaabbbbBBBBgggg(((()))) Pixel selectedTabBg(void); Returns the color used for the selected tab background. This color is set by the "selectedTabBackground" resource. If no resource value is specified, the normal tab background color is used. llllaaaabbbbeeeellllFFFFgggg(((()))) Pixel labelFg(void); Returns the color used for tab foregrounds (e.g. the tab lettering). This color is set by the "foreground" resource for the "tabLabel" widget created by VkTabPanel. When a bitmap is supplied as the pixmap, this color is used for the 1 bits. llllaaaabbbbeeeellllBBBBgggg(((()))) Pixel labelBg(void); Returns the color used for tab backgrounds. This color is set by the "background" resource for the "tabLabel" widget created by VkTabPanel. When a bitmap is supplied as the pixmap, this color is used for the 0 bits unless the tab is selected and a selectedTabBackground color resource exists. ggggcccc(((()))) GC gc(void); PPPPaaaaggggeeee 6666 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) Returns the X graphics context used for drawing the tabs. This may be useful to an application when it creates pixmaps and wants to use the same foreground and background colors as the tabs. This function is now deprecated, in favor of _g_e_t_S_e_l_e_c_t_e_d_T_a_b_B_g() and _g_e_t_U_n_s_e_l_e_c_t_e_d_T_a_b_B_g(). _g_c() is meaningful only with use3DTabs = FALSE. Applications that construct pixmaps for tab labels should set use3DTabs = TRUE and use the new functions to get their backgrounds. lllliiiinnnneeeeTTTThhhhiiiicccckkkknnnneeeessssssss(((()))) int lineThickness(void); Returns the line thickness used when drawing the tab edges. The line thickness defaults to 1, but can be set by the "lineThickness" resource of the VkTabPanel baseWidget. However, line thickness other than 1 may not render properly. ttttaaaabbbbHHHHeeeeiiiigggghhhhtttt(((()))) int tabHeight(void); Returns the height of the tab display area. This is the maximum display height for pixmaps. Pixmaps which are greater than this size will be truncated, and pixmaps which are smaller will be centered. This height can be specified in the constructor, or by the "tabHeight" resource of the VkTabPanel baseWidget, or by the font height of the "tabLabel" widget created by VkTabPanel. The total tab height is the tab display area height, plus the tab margin height, which is set by the "marginHeight" resource of the "tabLabel" widget created by VkTabPanel plus the "additionalMarginHeight" resource of the VkTabPanel baseWidget, which defaults to 2. The difference between the VkTabPanel component's height (or width, if vertically-oriented) and the true height of its tabs, is set by the "margin" resource of the VkTabPanel baseWidget, which defaults to 5. sssseeeelllleeeecccctttteeeeddddTTTTaaaabbbb(((()))) int selectedTab(void); Returns the index of the currently-selected tab. Tab indices start with zero. The maximum tab index, then, is size()-1. aaaarrrreeeeaaaa1111(((()))) Widget area1(void); PPPPaaaaggggeeee 7777 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) Returns the first work area. This is a Motif XmForm widget placed to the left of the tabs in a horizontal tab group, and above the tabs in a vertical group. The work area is separated from the tabs by the number of pixels specified by the "margin1" resource of the VkTabPanel baseWidget, which defaults to 5. aaaarrrreeeeaaaa2222(((()))) Widget area2(void); Returns the second work area. This is a Motif XmForm widget placed to the right of the tabs in a horizontal tab group, and below the tabs in a vertical group. The work area is separated from the tabs by the number of pixels specified by the "margin2" resource of the VkTabPanel baseWidget, which defaults to 5. aaaaddddddddTTTTaaaabbbb int addTab(char* label, void* clientData, Boolean sorted = False); void addTabs(char** labels, void** clientData, int numLabels, Boolean sorted = False); Adds a new tab to the group. The label is used as a resource lookup for the actual label string and if no resource match is found, used verbatim as the string. The clientData argument is for the application's convenience, and is returned in the VkTabCallbackStruct when that tab is selected. New tabs initially have a NULL pixmap. If the new tab is the first tab in the group, it is automatically selected. The index of the newly-added tab is returned. The addTabs form simply takes a list of new tabs to be added. The new tab is added to the end of the group unless the optional sorted argument is set to TRUE, in which case the tab is inserted before the first tab whose label alphabetically succeeds the new tab's label. If the tab added is the first tab in the panel, this tab will get selected and the tabSelectCallback will be invoked. sssseeeelllleeeeccccttttTTTTaaaabbbb(((()))) Boolean selectTab(int index, XEvent* event = NULL); Boolean selectTab(char* label, XEvent* event = NULL); Selects a tab. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned. If the tab couldn't be found or if the index is out of range, FALSE is returned. The optional event parameter is passed in the VkTabCallbackStruct for possible application use. If more than one tab match the label, the first one is selected. PPPPaaaaggggeeee 8888 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) rrrreeeemmmmoooovvvveeeeTTTTaaaabbbb(((()))) Boolean removeTab(int index); Boolean removeTab(char* label); Removes a tab from the list. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned. If the tab couldn't be found or if the index is out of range, FALSE is returned. If more than one tab match the label, the first one is selected. ttttaaaabbbbPPPPiiiixxxxmmmmaaaapppp(((()))) Boolean tabPixmap(int index, Pixmap* pixmap_return); Boolean tabPixmap(char* label, Pixmap* pixmap_return); Returns the pixmap associated with a tab. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned and the pixmap is returned through the pixmap_return argument. If the tab couldn't be found or if the index is out of range, FALSE is returned. If more than one tab match the label, the first one is selected. sssseeeettttTTTTaaaabbbbPPPPiiiixxxxmmmmaaaapppp(((()))) Boolean setTabPixmap(int index, Pixmap pixmap); Boolean setTabPixmap(char* label, Pixmap pixmap); Changes the pixmap associated with a tab. Use a NULL pixmap to eliminate the pixmap display. The tab's index or label can be used for selection. If the operation succeeds, TRUE is returned and the tabs are redrawn. If the tab couldn't be found or if the index is out of range, FALSE is returned. If more than one tab match the label, the first one is selected. sssseeeettttTTTTaaaabbbbLLLLaaaabbbbeeeellll(((()))) Boolean setTabLabel(int index, char* label); Changes the label associated with a tab. The label is used as a resource lookup for the actual label string and if no resource match is found, used verbatim as the string. If the operation succeeds, TRUE is returned and the tabs are redrawn. If the index is out of range, FALSE is returned. sssseeeettttTTTTaaaabbbbCCCClllliiiieeeennnnttttDDDDaaaattttaaaa(((()))) Boolean setTabClientData(int index, void* clientData); Changes the clientData associated with a tab. If the operation succeeds, TRUE is returned and the tabs are redrawn. If the index is out of range, FALSE is returned. PPPPaaaaggggeeee 9999 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) ggggeeeettttTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) int getTabWidth (int index=0); Returns the width of the tab whose index is passed. (Tabs are indexed from 0 to n-1.) ggggeeeettttMMMMaaaaxxxxTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) int getMaxTabWidth (); Gets the width that will be used to display the widest tab. This may not be wide enough to accommodate all labels if sssseeeettttTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) has been used. mmmmaaaattttcccchhhhTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) void matchTabWidth (VkTabPanel *tp=NULL, enum VK_TAB_MATCH_WIDTH = VK_DEFAULT); This introduces the concept of a tab panel match set. When a VkTabPanel's mmmmaaaattttcccchhhhTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) member is called, that VkTabPanel is assumed to be the set leader. It does not matter which tab panel you pick to be the set leader. All it does is some record-keeping. But you do need to be consistent about it. (The concept of a set leader is regarded as an unfortunate implementation limitation that we shall remove later if there is enough demand to do so.) If the ggggeeeettttMMMMaaaaxxxxTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) for ttttpppp is larger than that of the existing set, then the existing set's VkTabPanel's are each set to the new width. Otherwise ttttpppp is set to the width of the existing set. In either case, ttttpppp is added to the match set. mmmmaaaattttcccchhhhTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) sets widths using sssseeeettttTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))). /fBVK_DEFAULT is the only current setting for the enum. It is provided so we have an easy extension mechanism if we later need to use a different definition of matching. sssseeeettttTTTTaaaabbbbWWWWiiiiddddtttthhhh(((()))) void setTabWidth (int width=0); void setTabWidth (char *longestString); Normally, each tab is the right size to hold its label. That means that each tab in a single VkTabPanel is sized independently. PPPPaaaaggggeeee 11110000 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) sssseeeettttTTTTaaaabbbbWWWWiiiiddddtttthhhh sets the width of each tab for a single VkTabPanel to a single value. wwwwiiiiddddtttthhhh sets the width to that number of pixels. lllloooonnnnggggeeeessssttttSSSSttttrrrriiiinnnngggg sets the width to be enough to hold the specified string. The string does not need to be an actual tab label, although generally it will be. If the labels will be translated, be careful. The longest string in one language may not be the longest one in all languages. In most cases it will be easier to synchronize tab widths with mmmmaaaattttcccchhhhTTTTaaaabbbbWWWWiiiiddddtttthhhh. sssseeeettttTTTTaaaabbbbWWWWiiiiddddtttthhhh is provided for those cases where an application needs more control than mmmmaaaattttcccchhhhTTTTaaaabbbbWWWWiiiiddddtttthhhh gives. If sssseeeettttTTTTaaaabbbbWWWWiiiiddddtttthhhh((((0000)))), then tab width reverts to being calculated according to the length of the label. DDDDAAAATTTTAAAA MMMMEEEEMMMMBBBBEEEERRRR DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS ttttaaaabbbbSSSSeeeelllleeeeccccttttCCCCaaaallllllllbbbbaaaacccckkkk static const const char* tabSelectCallback; A callback function for detecting changes in the selected tab. The callData argument to the callback should be cast to a (VkTabCallbackStruct *). This structure returns the tab's label and clientData as passed to addTab, the current tab index, and the event which triggered the selection. The event may be NULL, if the user used the popup menu or the selection was programmatic. ttttaaaabbbbPPPPooooppppuuuuppppCCCCaaaallllllllbbbbaaaacccckkkk static const const char* tabPopupCallback; A callback function for detecting when the user right-buttons in a tab. The callData argument to the callback should be cast to a (VkTabCallbackStruct *). This structure returns the tab's label and clientData as passed to addTab, the current tab index, and the event which triggered the selection. IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCoooommmmppppoooonnnneeeennnntttt installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(), setDefaultResources(), getResources(), manage(), unmanage(), baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCaaaallllllllbbbbaaaacccckkkkOOOObbbbjjjjeeeecccctttt callCallbacks(), addCallback(), removeCallback(), removeAllCallbacks() PPPPaaaaggggeeee 11111111 VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) VVVVkkkkTTTTaaaabbbbPPPPaaaannnneeeellll((((3333xxxx)))) SEE ALSO VkComponent _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF PPPPaaaaggggeeee 11112222